Skip to content

<feature>[docs]: <description#4109

Open
zstack-robot-1 wants to merge 1 commit into
zsv_5.1.0from
sync/tao.gan/code-ZSV-12280
Open

<feature>[docs]: <description#4109
zstack-robot-1 wants to merge 1 commit into
zsv_5.1.0from
sync/tao.gan/code-ZSV-12280

Conversation

@zstack-robot-1
Copy link
Copy Markdown
Collaborator

Resolves: ZSV-12280

Change-Id: I63706d77756968716262686e75676f6179787362

sync from gitlab !10006

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 27, 2026

Review Change Stack

Warning

Review limit reached

@MatheMatrix, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 22 minutes and 28 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 19aa2663-c726-40dd-a649-3e695a7d15ca

📥 Commits

Reviewing files that changed from the base of the PR and between 0e41bc9 and bee363c.

📒 Files selected for processing (4)
  • docs/modules/core/nav.adoc
  • docs/modules/core/pages/live-primary-storage-migrate-volume.md
  • docs/modules/core/pages/primary-storage-migrate-volume.md
  • docs/modules/core/pages/ps-migrate-volume-relax-attached-data-volume.md

总体说明

本PR新增三份文档,完整阐述数据盘主存储冷迁移功能的现状和改进方案。

变更概览

存储迁移功能文档与设计

Layer / File(s) 摘要
导航与现有功能说明
docs/modules/core/nav.adoc, docs/modules/core/pages/primary-storage-migrate-volume.md
新增导航链接,并详细说明APIPrimaryStorageMigrateVolumeMsg的现有冷迁移API校验规则、存储类型差异化限制(Ceph/NFS须detach、SharedBlock允许Stopped、Shareable禁止)、迁移执行流程、候选主存储计算规则及Ceph/NFS强制detach的产品边界。
挂载态数据盘迁移放宽设计
docs/modules/core/pages/ps-migrate-volume-relax-attached-data-volume.md
系统阐述将Ceph/NFS数据盘迁移约束从"挂载即拒绝"调整为"VM Stopped时允许挂载态迁移"的完整设计,包括可行性与风险分析(强调startVm并发校验漏洞)、核心改造清单(拦截器、候选PS过滤、VM启动防护)、全局开关 relaxAttachedDataVolume 的灰度控制、以及工作量与验收标准。

序列图

已在隐藏审查堆栈中包含关键验证点的流程图。

代码审查工作量估算

🎯 2 (Simple) | ⏱️ ~12 分钟

诗歌

📚 文档春风拂过存储池,
冷迁数据盘终解锁。
Stopped的VM轻轻舞,
挂载态也能飞起来。
🐰 审查此卷,心如兔跃。

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive PR 标题不完整且缺乏实际描述信息,仅包含占位符 '<description' 而未提供具体的变更说明。 请完善 PR 标题,使其清晰、具体地概括主要变更内容,例如:'docs: 新增主存储卷迁移设计文档和放宽策略说明'。
✅ Passed checks (4 passed)
Check name Status Explanation
Description check ✅ Passed PR 描述包含了关键信息,包括 issue 跟踪号、提交变更标识和同步来源说明,与变更集相关。
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch sync/tao.gan/code-ZSV-12280

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
docs/modules/core/pages/ps-migrate-volume-relax-attached-data-volume.md (1)

102-111: 💤 Low value

为时间线代码块添加语言标识符。

建议为灾难场景时间线添加 text 语言标识符,以提高文档渲染的一致性。

♻️ 建议的修复
-```
+```text
 T0: VM Stopped, 数据盘 Status=Ready, installPath=ceph-A
 T1: 用户发起 Migrate → 进 volume sync 链;setStatus(Migrating)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/modules/core/pages/ps-migrate-volume-relax-attached-data-volume.md`
around lines 102 - 111, The fenced timeline code block lacks a language tag;
update the markdown in ps-migrate-volume-relax-attached-data-volume.md to use a
"text" fenced code block for the timeline (replace ``` with ```text) so the
disaster scenario timeline (the T0–T6 lines) renders consistently; locate the
block containing the T0..T6 lines and add the language identifier.
docs/modules/core/pages/primary-storage-migrate-volume.md (1)

51-62: 💤 Low value

为流程图代码块添加语言标识符。

静态分析工具建议为代码块指定语言标识符以提高可读性和渲染一致性。对于纯文本流程图,可使用 text 或留空。

♻️ 建议的修复
-```
+```text
 APIPrimaryStorageMigrateVolumeMsg
   ↓ StorageMigrationBase.handle
 PrimaryStorageMigrateVolumeMsg (本地消息)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/modules/core/pages/primary-storage-migrate-volume.md` around lines 51 -
62, Wrap the flowchart fenced code block with a language identifier (e.g.,
change the opening ``` to ```text) so the block is treated as plain text; update
the code block that contains the flow lines (starting with
"APIPrimaryStorageMigrateVolumeMsg" and including "StorageMigrationBase.handle",
"PrimaryStorageMigrateVolumeMsg", "MigrateDataVolumeOverlayMsg",
"MigrateVolumeOnPrimaryStorageMsg") to begin with ```text and keep the closing
``` unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/modules/core/nav.adoc`:
- Line 6: The navigation entry referencing
xref:primary-storage-migrate-volume.adoc[] points to a non-existent .adoc file
while the actual document is named primary-storage-migrate-volume.md; update the
nav entry to reference the real file or convert the target to an AsciiDoc file:
either change xref:primary-storage-migrate-volume.adoc[] to
xref:primary-storage-migrate-volume.md[] (or the correct AsciiDoc target) or
rename/convert primary-storage-migrate-volume.md to
primary-storage-migrate-volume.adoc so the xref resolves correctly.

---

Nitpick comments:
In `@docs/modules/core/pages/primary-storage-migrate-volume.md`:
- Around line 51-62: Wrap the flowchart fenced code block with a language
identifier (e.g., change the opening ``` to ```text) so the block is treated as
plain text; update the code block that contains the flow lines (starting with
"APIPrimaryStorageMigrateVolumeMsg" and including "StorageMigrationBase.handle",
"PrimaryStorageMigrateVolumeMsg", "MigrateDataVolumeOverlayMsg",
"MigrateVolumeOnPrimaryStorageMsg") to begin with ```text and keep the closing
``` unchanged.

In `@docs/modules/core/pages/ps-migrate-volume-relax-attached-data-volume.md`:
- Around line 102-111: The fenced timeline code block lacks a language tag;
update the markdown in ps-migrate-volume-relax-attached-data-volume.md to use a
"text" fenced code block for the timeline (replace ``` with ```text) so the
disaster scenario timeline (the T0–T6 lines) renders consistently; locate the
block containing the T0..T6 lines and add the language identifier.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b4062a8a-7da0-48fe-a2a1-80f60b7b65f8

📥 Commits

Reviewing files that changed from the base of the PR and between 8740fbd and 0e41bc9.

📒 Files selected for processing (3)
  • docs/modules/core/nav.adoc
  • docs/modules/core/pages/primary-storage-migrate-volume.md
  • docs/modules/core/pages/ps-migrate-volume-relax-attached-data-volume.md

Comment thread docs/modules/core/nav.adoc Outdated
** xref:scalability_secrets_part_1_asynchronous_architecture.adoc[]
** xref:stateless_services.adoc[]
** xref:message.adoc[]
** xref:primary-storage-migrate-volume.adoc[]
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# 检查 primary-storage-migrate-volume 文件的实际扩展名
fd -e md -e adoc 'primary-storage-migrate-volume' docs/modules/core/pages/

Repository: MatheMatrix/zstack

Length of output: 120


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== nav.adoc (lines 1-30) =="
nl -ba docs/modules/core/nav.adoc | sed -n '1,30p'

echo
echo "== other xref patterns in docs/modules/core (adoc/md) =="
rg -n "xref:.*\.(adoc|md)\[\]" docs/modules/core --glob='*.adoc' --glob='*.adoc*' --glob='*.md' || true
rg -n "xref:" docs/modules/core/nav.adoc || true

echo
echo "== primary-storage-migrate-volume.md header (first 80 lines) =="
nl -ba docs/modules/core/pages/primary-storage-migrate-volume.md | sed -n '1,80p' || true

Repository: MatheMatrix/zstack

Length of output: 151


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== nav.adoc (around line 6) =="
# try cat -n first; fallback to awk if needed
if command -v cat >/dev/null 2>&1 && cat -n docs/modules/core/nav.adoc >/dev/null 2>&1; then
  cat -n docs/modules/core/nav.adoc | sed -n '1,30p'
else
  awk '{print NR "\t" $0}' docs/modules/core/nav.adoc | sed -n '1,30p'
fi

echo
echo "== xref usage patterns in docs/modules/core (sample) =="
# Search within nav and pages for extension usage
rg -n "xref:.*\\.adoc\\[\\]" docs/modules/core || true
rg -n "xref:.*\\.md\\[\\]" docs/modules/core || true

echo
echo "== primary-storage-migrate-volume.md header (first 120 lines) =="
cat -n docs/modules/core/pages/primary-storage-migrate-volume.md | sed -n '1,120p'

Repository: MatheMatrix/zstack

Length of output: 6985


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== md pages basenames under docs/modules/core/pages =="
# list md files and strip extension
fd -e md --type f '' docs/modules/core/pages/ 2>/dev/null | awk -F/ '{print $NF}' | sed 's/\.md$//' | sort | head -n 200

echo
echo "== nav.adoc xref targets that end with .adoc[] =="
rg -o "xref:[^\\]]+\\.adoc\\[\\]" docs/modules/core/nav.adoc | sort -u

echo
echo "== for each md basename, whether nav.adoc references it as .adoc[] =="
python3 - <<'PY'
import subprocess, re, os, sys, textwrap, json
nav_path="docs/modules/core/nav.adoc"
md_files=subprocess.check_output(["bash","-lc", "fd -e md --type f '' docs/modules/core/pages/ 2>/dev/null"], text=True).splitlines()
bases=[os.path.basename(p).replace(".md","") for p in md_files if p.strip()]
nav=open(nav_path,'r',encoding='utf-8').read()
for b in sorted(bases):
    pat=f"xref:{b}.adoc[]"
    print(("OK " if pat in nav else "NO ") + pat)
PY

Repository: MatheMatrix/zstack

Length of output: 751


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== md pages basenames under docs/modules/core/pages =="
fd -e md --type f '' docs/modules/core/pages/ 2>/dev/null | awk -F/ '{print $NF}' | sed 's/\.md$//' | sort

echo
echo "== nav.adoc xref targets (unique, .adoc[] form) =="
rg -o "xref:[^\\]]+\\.adoc\\[\\]" docs/modules/core/nav.adoc | sort -u

echo
echo "== for each md basename, whether nav.adoc references it as .adoc[] =="
python3 - <<'PY'
import subprocess, os
nav_path="docs/modules/core/nav.adoc"
nav=open(nav_path,'r',encoding='utf-8').read()
md_out=subprocess.check_output(["bash","-lc","fd -e md --type f '' docs/modules/core/pages/ 2>/dev/null"], text=True)
bases=[]
for p in md_out.splitlines():
    p=p.strip()
    if not p: 
        continue
    bases.append(os.path.basename(p).removesuffix(".md"))
for b in sorted(set(bases)):
    pat=f"xref:{b}.adoc[]"
    print(("OK " if pat in nav else "NO ") + pat)
PY

Repository: MatheMatrix/zstack

Length of output: 752


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== md pages basenames under docs/modules/core/pages =="
fd -e md --type f '' docs/modules/core/pages/ 2>/dev/null | awk -F/ '{print $NF}' | sed 's/\.md$//' | sort

echo
echo "== nav.adoc xref targets (unique, .adoc[] form) =="
rg -o "xref:[^\\]]+\\.adoc\\[\\]" docs/modules/core/nav.adoc | sort -u

echo
echo "== for each md basename, whether nav.adoc references it as .adoc[] =="
python3 - <<'PY'
import subprocess, os
nav_path="docs/modules/core/nav.adoc"
nav=open(nav_path,'r',encoding='utf-8').read()
md_out=subprocess.check_output(["bash","-lc","fd -e md --type f '' docs/modules/core/pages/ 2>/dev/null"], text=True)
bases=[]
for p in md_out.splitlines():
    p=p.strip()
    if not p:
        continue
    bases.append(os.path.basename(p).removesuffix(".md"))
for b in sorted(set(bases)):
    pat=f"xref:{b}.adoc[]"
    print(("OK " if pat in nav else "NO ") + pat)
PY

Repository: MatheMatrix/zstack

Length of output: 752


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== references to primary-storage-migrate-volume.* =="
rg -n "primary-storage-migrate-volume(\.adoc|\.(md))?\[\]" docs || true
rg -n "primary-storage-migrate-volume" docs/modules/core | head -n 50 || true

echo
echo "== references to ps-migrate-volume-relax-attached-data-volume.* =="
rg -n "ps-migrate-volume-relax-attached-data-volume(\.adoc|\.(md))?\[\]" docs || true
rg -n "ps-migrate-volume-relax-attached-data-volume" docs/modules/core | head -n 50 || true

echo
echo "== whether any .adoc counterpart exists for primary page =="
fd -e adoc 'primary-storage-migrate-volume' docs/modules/core || true

Repository: MatheMatrix/zstack

Length of output: 989


🌐 Web query:

Asciidoctor xref:filename.adoc[] can it reference a file whose source extension is .md? xref:primary-storage-migrate-volume.adoc[] with source primary-storage-migrate-volume.md

💡 Result:

Yes—if you use xref for inter-document references, the xref syntax and resolution are based on AsciiDoc “document names” (typically ending with.adoc), and the file extension used in the generated link can be controlled via the relfilesuffix attribute. However, referencing an AsciiDoc xref target whose source file extension is.md is not supported as a normal “inter-document xref to a source document” unless your toolchain treats that.md file as an AsciiDoc document (e.g., it’s converted/registered into the same document set). Asciidoctor’s documentation describes inter-document xrefs in terms of linking to other AsciiDoc source documents, and the default link suffix behavior is tied to the generated output (e.g.,.html for html5) and can be overridden to point to source files like.adoc using relfilesuffix [1][2]. Practical guidance for your example: 1) With pure AsciiDoc processing, use the AsciiDoc source name in xref, e.g. xref:primary-storage-migrate-volume.adoc[] (and optionally an anchor like #some-id). The xref syntax expects the document name/anchor pattern and is designed around AsciiDoc inter-document xrefs [3][4]. 2) If you want the generated link to point at a source file extension other than what the backend would normally emit (e.g., point to.adoc instead of.html), set:relfilesuffix: appropriately [2]. This controls the extension in the created link, not whether AsciiDoc can cross-reference a non-AsciiDoc (.md) source document. So for your stated case (xref:primary-storage-migrate-volume.adoc[] with source primary-storage-migrate-volume.md): - If the target file is truly only Markdown (.md) and is not part of the AsciiDoc document set, Asciidoctor will not be able to resolve the xref as an inter-document reference to that source document (you’d need to convert it to.adoc or include it via your documentation pipeline). The docs explicitly frame xrefs as references between AsciiDoc source documents within a document set, and show.adoc as the expected source-document name pattern [4].

Citations:


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== repo-wide search for primary-storage-migrate-volume.adoc =="
fd -e adoc 'primary-storage-migrate-volume' . || true

echo
echo "== existence of nav targets as .adoc under docs/modules/core/pages (expected) =="
for f in index in-process-microservice scalability_secrets_part_1_asynchronous_architecture stateless_services message primary-storage-migrate-volume; do
  echo "-- $f"
  fd -e adoc "${f}" docs/modules/core/pages/ 2>/dev/null || true
  fd -e md "${f}" docs/modules/core/pages/ 2>/dev/null || true
done

Repository: MatheMatrix/zstack

Length of output: 679


修正导航条目 xref 的目标扩展名/文档名
docs/modules/core/nav.adoc 第 6 行引用 xref:primary-storage-migrate-volume.adoc[],但仓库中不存在 primary-storage-migrate-volume.adoc,仅存在 docs/modules/core/pages/primary-storage-migrate-volume.md;按当前 nav.adoc 中其它条目的 .adoc[] 引用约定,这会导致该导航链接无法解析。建议将该页面统一为 .adoc(或相应地调整构建/引用到实际被 AsciiDoc 解析的文档名)。

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/modules/core/nav.adoc` at line 6, The navigation entry referencing
xref:primary-storage-migrate-volume.adoc[] points to a non-existent .adoc file
while the actual document is named primary-storage-migrate-volume.md; update the
nav entry to reference the real file or convert the target to an AsciiDoc file:
either change xref:primary-storage-migrate-volume.adoc[] to
xref:primary-storage-migrate-volume.md[] (or the correct AsciiDoc target) or
rename/convert primary-storage-migrate-volume.md to
primary-storage-migrate-volume.adoc so the xref resolves correctly.

@MatheMatrix MatheMatrix force-pushed the sync/tao.gan/code-ZSV-12280 branch from 0e41bc9 to 13a9987 Compare May 27, 2026 02:47
Resolves: ZSV-12280

Change-Id: I63706d77756968716262686e75676f6179787362
@MatheMatrix MatheMatrix force-pushed the sync/tao.gan/code-ZSV-12280 branch from 13a9987 to bee363c Compare May 27, 2026 02:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants